SuperHack

home *** CD-ROM | disk | FTP | other *** search

/ SuperHack / SuperHack CD.bin / CODING / SOUND / GUSLIB.ZIP / GUSLIB.DOC < prev next >

Wrap

Text File | 1994-08-26 | 15.5 KB | 440 lines

GusLib v1.0 By Paul Kimbrel Aug 17, 1994 Documentation Short Description ------------------------------------- GusLib is a public domain/royalty free programming library for the Gravis UltraSound sound card. It's purpose is to allow programmers easy access to the basic functions of the GUS. The library was mainly written for assembly language use but can be easily used with C,C++,Pascal, and other languages. It's features are: Direct DRAM I/O functions DMA DRAM Output Playback routines Register I/O functions This library is designed primarily for output only. Some functions could be used for input as well, though programming experience with the GUS would be required. Disclaimer ------------------------------------- This program is given as is. It is subject to change with out notice or permission. I make no claims as to it's usability or workability. I've made all attempts to test it as much as possible, but I claim no responsibility for any damages caused by this program. In other words, it works here, so if doesn't work there, I can't help it. Enough of the bad guy stuff: I'll be happy to help with any problems and would like to know if any flaws in the programming are found. I'm always looking to improve my programs, so if you have any recommendations, please get a hold of me and let me know. As far as it's status as a program, it's public domain which means you can do just about anything to it you want. I encourage you to dig into the code and make your alterations to it as you wish. Copy the code, use it in other programs, use it as a reference for other GUS applications, whatever. This program is yours to do with as you please. Use it in your games, applications, etc., and don't worry about royalty or credit (although, just mentioning my name would be nice <g>). If you do use my program in any of your applications, please drop me a note, just so I can keep track of things (and for personal gratification). Files ------------------------------------- The following files are included in the GUSLIB library: GUSLIB.ASM - Source code to GUSLIB GUSLIB.OBJ - Object code to GUSLIB for linking GUSLIB.LIB - Library file to GUSLIB for linking GUSLIB.DOC - Documentation for GUSLIB PLAYVOC.EXE - Sample program using GUSLIB (plays back .VOC files) PLAYVOC.ASM - Sample source code using GUSLIB Stuff that might be important (?) ------------------------------------- Okay, I'll admit it - I hate commenting my programs - especially when I've been working for a solid week on it. It gets to the point of "I could care less if I know how it works just so long as it works." I'm sitting here with an actual working model on my computer and really don't want to go through and comment, so I'm going to let it be for now. However, you can look for more comments in future revisions of the program (I can almost guarantee that there will be). If you have any questions at all about the program, you can find me in the 80XXX echo on Fidonet (as Paul Kimbrel), you can net-mail me at 1:232/10 (again, to Paul Kimbrel), or e-mail me via the internet at dkimbrel@heartland.bradley.edu All answer ALL questions even if it's to say that I haven't the foggiest idea what-so-ever. I'll be working on a better version, but this will at least get some people (including myself) working. I hope you find some kind of usefulness from this program. An IMPORTANT note concerning the DMA channels! - MUST READ!!!!! ------------------------------------- Please note that the only two channels that this program will work with are the 8 bit channels (1 and 3). GUSLIB will allow for the 16 bit channels (5,6 and 7), yet I've never worked with them before. As a result, I make NO assumtions as to if they work or not. If you want to try - go for it, just let it be known that I have tried (yet)... Functions ------------------------------------- To use these functions, simply fill the BX register with the function number and all other registers with the appropriate information (depending on the function). Next, call the procedure GUSLIB. When the function has been executed, a return code will come back in the AX register. If AX reads 00h, then the function was executed successfully. Otherwise, AX contains the error code. Function 00h - Init_Gus ------------------------------------- Short Description: Initializes and sets up the GUS Registers on entry: BX = 0000h Registers on return: AX = Error Code - 00h - No Error 01h - Bad Environmental Variable 02h - Illegal IRQ in Environmental Variable 03h - Illegal DMA channel in Environmental Variable 04h - GUS Reset error 05h - DRAM I/O Error Extended Description: This function preforms several tasks. It first searches and processes the 'ULTRASND=' environmental variable. Then it checks to make sure that all the information in the variable is correct. Third, it resets the GUS. Fourth, it makes sure that the DRAM is okay. Finally, it sets up the library's ISR for the IRQ and programs the computer's PIC (how's THAT for initials!). When the ISR is setup, your program MUST run the deinitialization function do undo what the initialization does. The best thing to do is write your program to ALWAYS execute the deinitialation function before it exits. The functions are made so that it won't undo the ISR if it isn't set up. In other words, if you call the deinitalization function and there's nothing for it to do, it'll automatically return with out doing anything, making it easier for you to keep track of things. Function 01h - Deinit_Gus ------------------------------------- Short Description: Deinitializes and shuts down the GUS Registers on entry: BX = 0001h Registers on return: None Extended Description: This function basically undoes what function 00h does. If function 00h isn't executed, then this function will automatically return with out doing anything. It's best to call this function right before you exit no matter what the situation is. This makes keeping track of the initialization process easier (IOW - you really don't have to). Function 02h - Poke ------------------------------------- Short Description: Pokes data directly into the GUS's memory. Registers on entry: BX = 0002h AL = Value to poke SI:DI = Linear Address in GUS memory. Registers on return: None Extended Description: This function pokes data directly into the GUS's DRAM. SI:DI point to the absolute linear address. Keep in mind that the GUS can only address 1 MEG of memory, so only the lower 20 bits should contain data; all other bits should be set to 0. NOTE: The value in AL is put into memory AS IS. There is no two's- compliment conversion in this function. If a conversion is necessary, you must do it to the value before you call this function. Function 03h - Peek ------------------------------------- Short Description: Peeks data directly from the GUS's memory. Registers on entry: SI:DI = Linear Address in GUS memory Registers on return: BX = 0003h AL = Data at SI:DI Extended Description: This function peeks data directly from the GUS's memory. It's address scheme is the same as that in function 02h. NOTE: The value returned in AL is read AS IS. There is no two's- compliment conversion in this function. If a conversion is necessary, you must do it to the value after you call this function. Function 04h - Set_Active ------------------------------------- Short Description: Sets the number of active voices on the GUS. Registers on entry: BX = 0004h AL = Number of Pages (14-32) Registers on return: None Extended Description: This function sets the number of active voices on the GUS. An explanation of this function is beyond the scope of this documentation. Just keep in mind that you don't using any voices beyond the number that you have set with this function. NOTE: The fewer voices you have, the better the sound quality will be. For more information, see the Gravis Ultrasound SDK. Function 05h - Download_Sound ------------------------------------- Short Description: Uses PC's DMA to send a sound sample to GUS's memory. Registers on entry: BX = 0005h CL = Wait Toggle (0 = no; 1 = yes) DI = GUS DRAM Address (upper 16 bits) ES:SI = PC segment:offset address of sample DX:AX = Size of sample Registers on return: AX = Error Code - 00h - No Error 01h - KeyBoard interrupt (if CL = 1 on entry) 02h - DMA still busy Extended Description: This dumps a sample that is stored in PC memory to the GUS memory via the DMA channel. Note that the GUS DRAM Address (in DI) is only the upper 16 bits of the address. Since the entire linear address is 20 bits, you must take your absolute address and divide it by 16 (that's 16 decimal). As you may have noticed, your DMA address will have to on a 16 byte boundary. The wait toggle specifies to the routine if you want to it to wait until the DMA is done or to just return immediately. CASE: CL = 0 The routine will return as soon as the DMA has started its transfer. No other DMA transfers can take place until the DMA is finished. To check the status of the DMA, execute function 6 or re-execute this function. If you re-execute this function and get an error code of 2, then the DMA is still busy. CASE: CL = 1 The routine will wait until the DMA has finished its transfer before returning. For safety purposes, the program checks the keyboard during the wait. If a key is hit, the function will return and will send back an error code of 1. Function 06h - Dma_Status ------------------------------------- Short Description: Checks on the status of the DMA download (function 5) Registers on entry: BX = 0006h Registers on return: AX = Status Extended Description: Returns the status of the DMA download (function 5). It returns a value of 0 if the DMA is free and available for downloading. If it returns a value of 1, a DMA transfer is taking place and the channel is busy. Function 07h - Set_Volume ------------------------------------- Short Description: Sets the volume of a specific voice. Registers on entry: BX = 0007h AX = Volume (0-4095) CL = Voice (0-active voices) Registers on return: None Extended Description: NOTE: The voice ranges from 0 to the number of active voices-1. For example, if the number of active voices is 14, then the available voices would be 0-13. Likewise, if the number of active voices is 32, then the available voices would be 0-31. Function 08h - Set_Freq ------------------------------------- Short Description: Sets the sampling frequency of a specific voice. Registers on entry: BX = 0008h AX = Frequency (1-44100) CL = Voice Registers on return: None Extended Description: NOTE: The voice ranges from 0 to the number of active voices-1. For example, if the number of active voices is 14, then the available voices would be 0-13. Likewise, if the number of active voices is 32, then the available voices would be 0-31. Function 09h - Set_Loop ------------------------------------- Short Description: Sets the loop back condition of the specific voice. Registers on entry: BX = 0009h AL = Loop control register value (recommended value = 3) CL = Voice Registers on return: None Extended Description: NOTE: The voice ranges from 0 to the number of active voices-1. For example, if the number of active voices is 14, then the available voices would be 0-13. Likewise, if the number of active voices is 32, then the available voices would be 0-31. NOTE: Loop control is beyond the scope of this manual. For more information on loop control, read the Gravis Ultrasound SDK. To disable the loop control, write the value 3 to the function. This is the recommended action before using a voice (to clear any old values). Function 0ah - Set_Start ------------------------------------- Short Description: Sets the starting address (in GUS memory) of the sample. Registers on entry: BX = 000ah DX:AX = Linear 20-bit address in GUS memory CL = Voice Registers on return: None Extended Description: NOTE: The voice ranges from 0 to the number of active voices-1. For example, if the number of active voices is 14, then the available voices would be 0-13. Likewise, if the number of active voices is 32, then the available voices would be 0-31. This sets the starting location for the particular voice. GUSLIB auto- matically adjusts the <current address> register to fit this value. When you start playback of the voice, the playback will start at the value in DX:AX. When the voice has stopped or has been stopped (manually), GUSLIB will readjust the <current address> register so that it will restart at this address each time. Function 0bh - Set_End ------------------------------------- Short Description: Sets the ending address (in GUS memory) of the sample. Registers on entry: BX = 000bh DX:AX = Linear 20-bit address in GUS memory CL = Voice Registers on return: None Extended Description: NOTE: The voice ranges from 0 to the number of active voices-1. For example, if the number of active voices is 14, then the available voices would be 0-13. Likewise, if the number of active voices is 32, then the available voices would be 0-31. This sets the ending address of the voice. When the playback routine is executed, the GUS will start playback at the <start address> and will stop when it reaches this address. Function 0ch - Play_Voice ------------------------------------- Short Description: Starts playback of a specific voice Registers on entry: BX = 000ch AH = Control register (Use 00h for normal operation) AL = Voice Registers on return: None Extended Description: This function starts the playback for a specific voice. To start a normal playback (forward direction, no loop, irq's on, etc.), Simply write 00h to the Control register (in AH). The function will filter out unwanted information in the control register and set important information, so only worry about those bits in which you can modify. The operation of the control register is beyond the scope of this document; Please refer to Gravis Ultrasound SDK for more information. Function 0dh - Stop_Voice ------------------------------------- Short Description: Manually stops the playback of a specific voice. Registers on entry: BX = 000dh AL = Voice Registers on return: None Extended Description: This function will manually stop and reset the specified voice. Function 0eh - Voice_Status ------------------------------------- Short Description: Returns the playback status of a specific voice. Registers on entry: BX = 000eh AL = Voice Registers on return: AX = Status - 00h = Voice is in playback mode 01h = Voice has stopped (not in playback mode)